Description

Fix the v0.79.0 phase-handoff race: ctx.NewSession invoked from an
OnAgentEnd handler always failed with "cannot start new session while agent is busy" because AgentEnd is emitted from inside the agent loop —
before drainQueue clears app.busy — and any post-turn tooling
(formatters, on-save linters, hidden tool calls) keeps the busy window open
for seconds to minutes after that.

Instead of failing fast, RequestNewSessionFromExtension now blocks until
the agent is genuinely idle (up to a generous 10-minute internal timeout)
and then sends the NewSessionRequestEvent. The wait is built on a new
App.WaitForIdle(timeout) primitive backed by a per-busy-cycle idleCh
channel that is closed on every busy → idle transition. All existing busy
mutations are funnelled through a single setBusyLocked helper so the
channel always tracks the flag.

A sentinel ErrAgentBusy is shared between internal/app and
internal/extensions (and exposed to Yaegi as ext.ErrAgentBusy), so
extension authors can detect timeouts with errors.Is(err, ext.ErrAgentBusy)
instead of substring-matching the error message.

Before:

api.OnAgentEnd(func(_ ext.AgentEndEvent, ctx ext.Context) {
    go func() {
        // Always fails: "cannot start new session while agent is busy"
        _ = ctx.NewSession("next phase")
    }()
})

After: the same code just works — NewSession waits for the agent to
settle (including any post-turn hooks) and then switches sessions.

Fixes #63

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactor / cleanup

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (godoc on
  ctx.NewSession, sentinel error doc, example comment update)
• My changes generate no new warnings
• I have added tests that prove my fix is effective
• New and existing unit tests pass locally with my changes
  (go test -race ./... clean, golangci-lint run clean)
• Any dependent changes have been merged and published

Additional Information

Files changed

• internal/app/app.go — ErrAgentBusy sentinel,
  DefaultNewSessionIdleWait, idleCh field, setBusyLocked chokepoint,
  WaitForIdle, idleSnapshot; RequestNewSessionFromExtension now waits
  for idle instead of failing fast.
• internal/extensions/api.go — declare shared ErrAgentBusy; expand the
  NewSession godoc to describe the wait-then-send semantics and remind
  authors to call it from a goroutine.
• internal/extensions/symbols.go — expose ext.ErrAgentBusy to Yaegi.
• examples/extensions/phase-handoff.go — update the comment around the
  go func() { ctx.NewSession(...) }() call to reflect the new behaviour.
• internal/app/app_test.go — 7 new regression tests covering the
  already-idle fast path, blocks-until-drain, timeout → ErrAgentBusy,
  zero-timeout-waits-indefinitely, app-close release, headless guard, and
  idleCh channel transitions.

Backward compatibility

• The public/extension API surface is unchanged. ctx.NewSession now
  succeeds in cases that previously errored; it still returns the same
  error shapes for non-busy failure modes (no TUI attached, before-hook
  cancellation, session-file failure).
• Old extensions that substring-matched "agent is busy" will continue
  to match because the returned error still contains that phrase
  (fmt.Errorf("cannot start new session: %w", ErrAgentBusy)), but new
  code should migrate to errors.Is(err, ext.ErrAgentBusy).

Summary by CodeRabbit

• Bug Fixes

  • Fixed race conditions in automatic agent phase transitions for more reliable session handoffs.
  • Enhanced idle/busy state synchronization across concurrent operations.

• Documentation

  • Clarified session switching behavior and agent busy state handling.

• Tests

  • Added comprehensive test coverage for idle/busy signaling and phase transitions.